.TH std::locale 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::locale \- std::locale

.SH Synopsis
   Defined in header <locale>
   class locale;

   An object of class std::locale is an immutable indexed set of immutable facets. Each
   stream object of the C++ input/output library is associated with an std::locale
   object and uses its facets for parsing and formatting of all data.
   In addition, a locale object is associated with each std::basic_regex object.
   \fI(since C++11)\fP Locale objects can also be used as predicates that perform string
   collation with the standard containers and algorithms and can be accessed directly
   to obtain or modify the facets they hold.

   Each locale constructed in a C++ program holds at least the following standard
   facets (i.e. std::has_facet returns true for all these facet types), but a program
   may define additional specializations or completely new facets and add them to any
   existing locale object.

                                     Supported facets
   std::collate<char>       std::codecvt<char, char, std::mbstate_t>
   std::collate<wchar_t>    std::codecvt<wchar_t, char, std::mbstate_t>
                            std::codecvt<char16_t, char8_t, std::mbstate_t> (since
   std::ctype<char>         C++20)
   std::ctype<wchar_t>      std::codecvt<char32_t, char8_t, std::mbstate_t> (since
                            C++20)
   std::money_get<char>     std::moneypunct<char>
   std::money_get<wchar_t>  std::moneypunct<char, true>
   std::money_put<char>     std::moneypunct<wchar_t>
   std::money_put<wchar_t>  std::moneypunct<wchar_t, true>
   std::num_get<char>
   std::num_get<wchar_t>    std::numpunct<char>
   std::num_put<char>       std::numpunct<wchar_t>
   std::num_put<wchar_t>
   std::time_get<char>
   std::time_get<wchar_t>   std::messages<char>
   std::time_put<char>      std::messages<wchar_t>
   std::time_put<wchar_t>
                                    Deprecated facets
   std::codecvt<char16_t, char, std::mbstate_t> \fI(since C++11)\fP(deprecated in C++20)
   std::codecvt<char32_t, char, std::mbstate_t> \fI(since C++11)\fP(deprecated in C++20)

   Internally, a locale object is implemented as if it is a reference-counted pointer
   to an array (indexed by std::locale::id) of reference-counted pointers to facets:
   copying a locale only copies one pointer and increments several reference counts. To
   maintain the standard C++ library thread safety guarantees (operations on different
   objects are always thread-safe), both the locale reference count and each facet
   reference count are updated in a thread-safe manner, similar to std::shared_ptr.

.SH Member types

            the facet index type: each facet class must declare or inherit a public
   id       static member of this type
            \fI(class)\fP
            the base class for all facet categories: each facet of any category is
   facet    derived from this type
            \fI(class)\fP
   category int
            \fI(typedef)\fP

.SH Member objects

   none     a zero value of type category indicating no facet category
   \fB[static]\fP \fI(public static member constant)\fP
   collate  a bitmask value of type category indicating the collate facet category
   \fB[static]\fP \fI(public static member constant)\fP
   ctype    a bitmask value of type category indicating the ctype facet category
   \fB[static]\fP \fI(public static member constant)\fP
   monetary a bitmask value of type category indicating the monetary facet category
   \fB[static]\fP \fI(public static member constant)\fP
   numeric  a bitmask value of type category indicating the numeric facet category
   \fB[static]\fP \fI(public static member constant)\fP
   time     a bitmask value of type category indicating the time facet category
   \fB[static]\fP \fI(public static member constant)\fP
   messages a bitmask value of type category indicating the messages facet category
   \fB[static]\fP \fI(public static member constant)\fP
   all      collate | ctype | monetary | numeric | time | messages
   \fB[static]\fP \fI(public static member constant)\fP

   std::locale member functions expecting a category argument require one of the
   category values defined above, or the union of two or more such values. The LC
   constants are not accepted.

.SH Member functions

   constructor        constructs a new locale
                      \fI(public member function)\fP
                      destructs the locale and the facets whose reference count becomes
   destructor         zero
                      \fI(public member function)\fP
   operator=          replaces a locale
                      \fI(public member function)\fP
                      constructs a locale with compile-time identified facet copied
   combine            from another locale
                      \fI(public member function)\fP
   name               returns the name of the locale or "*" if unnamed
                      \fI(public member function)\fP
   operator==         equality comparison between locale objects
   operator!=         \fI(public member function)\fP
   (removed in C++20)
                      lexicographically compares two strings using this locale's
   operator()         collate facet
                      \fI(public member function)\fP
   global             changes the global locale
   \fB[static]\fP           \fI(public static member function)\fP
   classic            obtains a reference to the "C" locale
   \fB[static]\fP           \fI(public static member function)\fP

.SH Example

   Demonstrates the typical prologue of a locale-sensitive program (cross-platform).


// Run this code

 #include <iostream>
 #include <locale>

 int main()
 {
     std::wcout << "User-preferred locale setting is "
                << std::locale("").name().c_str() << '\\n';
     // on startup, the global locale is the "C" locale
     std::wcout << 1000.01 << '\\n';

     // replace the C++ global locale and the "C" locale with the user-preferred locale
     std::locale::global(std::locale(""));
     // use the new global locale for future wide character output
     std::wcout.imbue(std::locale());

     // output the same number again
     std::wcout << 1000.01 << '\\n';
 }

.SH Possible output:

 User-preferred locale setting is en_US.UTF8
 1000.01
 1,000.01

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to            Behavior as published               Correct behavior
   LWG 340 C++98      the set of standard facets that all locales  made clear
                      need to hold was unclear
   LWG 347 C++98      parameters of type category could accept LC  not accepted anymore
                      constants

.SH See also

   use_facet obtains a facet from a locale
             \fI(function template)\fP
   has_facet checks if a locale implements a specific facet
             \fI(function template)\fP
   imbue     sets locale
             \fI(public member function of std::ios_base)\fP
   getloc    returns current locale
             \fI(public member function of std::ios_base)\fP
